home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 85 / CD Actual 85 Febrero 2004.iso / Experto / Apache / apache_2.0.48-win32-x86-no_ssl.msi / Data.Cab / F252675_mod_auth_digest.xml < prev    next >
Encoding:
Extensible Markup Language  |  2003-04-23  |  13.0 KB  |  318 lines
  1. <?xml version="1.0"?>
  2. <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
  3. <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
  4. <modulesynopsis metafile="mod_auth_digest.xml.meta">
  5.  
  6. <name>mod_auth_digest</name>
  7. <description>User authentication using MD5
  8.     Digest Authentication.</description>
  9. <status>Experimental</status>
  10. <sourcefile>mod_auth_digest.c</sourcefile>
  11. <identifier>auth_digest_module</identifier>
  12.  
  13. <summary>
  14.     <p>This module implements HTTP Digest Authentication. However, it
  15.     has not been extensively tested and is therefore marked
  16.     experimental.</p>
  17. </summary>
  18.  
  19. <seealso><directive module="core">AuthName</directive></seealso>
  20. <seealso><directive module="core">AuthType</directive></seealso>
  21. <seealso><directive module="core">Require</directive></seealso>
  22. <seealso><directive module="core">Satisfy</directive></seealso>
  23.  
  24. <section id="using"><title>Using Digest Authentication</title>
  25.  
  26.     <p>Using MD5 Digest authentication is very simple. Simply set
  27.     up authentication normally, using <code>AuthType Digest</code> and
  28.     <directive module="mod_auth_digest">AuthDigestFile</directive> instead
  29.     of the normal <code>AuthType Basic</code> and <directive
  30.     module="mod_auth">AuthUserFile</directive>; also, replace any <directive
  31.     module="mod_auth">AuthGroupFile</directive> with <directive
  32.     module="mod_auth_digest">AuthDigestGroupFile</directive>. Then add a
  33.     <directive module="mod_auth_digest">AuthDigestDomain</directive> directive
  34.     containing at least the root URI(s) for this protection space.</p>
  35.  
  36.     <p>Appropriate user (text) files can be created using the
  37.     <a href="../programs/htdigest.html">htdigest</a> tool.</p>
  38.  
  39.     <example><title>Example:</title>
  40.       <Location /private/><br />
  41.       <indent>
  42.         AuthType Digest<br />
  43.         AuthName "private area"<br />
  44.         AuthDigestDomain /private/ http://mirror.my.dom/private2/<br />
  45.         AuthDigestFile /web/auth/.digest_pw<br />
  46.         Require valid-user<br />
  47.       </indent>
  48.       </Location>
  49.     </example>
  50.  
  51.     <note><title>Note</title> 
  52.     <p>Digest authentication provides a more secure password system
  53.     than Basic authentication, but only works with supporting
  54.     browsers. As of November 2002, the major browsers that support digest
  55.     authentication are <a href="http://www.opera.com/">Opera</a>, <a
  56.     href="http://www.microsoft.com/windows/ie/">MS Internet
  57.     Explorer</a> (fails when used with a query string), <a
  58.     href="http://www.w3.org/Amaya/">Amaya</a>, <a
  59.     href="http://www.mozilla.org">Mozilla</a> and <a
  60.     href="http://channels.netscape.com/ns/browsers/download.jsp"
  61.     >Netscape</a> since version 7. Since digest authentication is not
  62.     as widely implemented as basic authentication, you should use it only
  63.     in controlled environments.</p>
  64.     </note>
  65. </section>
  66.  
  67. <directivesynopsis>
  68. <name>AuthDigestFile</name>
  69. <description>Location of the text file containing the list
  70. of users and encoded passwords for digest authentication</description>
  71. <syntax>AuthDigestFile <var>file-path</var></syntax>
  72. <contextlist><context>directory</context><context>.htaccess</context>
  73. </contextlist>
  74. <override>AuthConfig</override>
  75.  
  76. <usage>
  77.     <p>The <directive>AuthDigestFile</directive> directive sets the
  78.     name of a textual file containing the list of users and encoded
  79.     passwords for digest authentication. <var>File-path</var> is the
  80.     absolute path to the user file.</p>
  81.  
  82.     <p>The digest file uses a special format. Files in this format
  83.     can be created using the <a
  84.     href="../programs/htdigest.html">htdigest</a> utility found in
  85.     the <code>support/</code> subdirectory of the Apache distribution.</p>
  86. </usage>
  87. </directivesynopsis>
  88.  
  89. <directivesynopsis>
  90. <name>AuthDigestGroupFile</name>
  91. <description>Name of the text file containing the list of groups
  92. for digest authentication</description>
  93. <syntax>AuthDigestGroupFile <var>file-path</var></syntax>
  94. <contextlist><context>directory</context><context>.htaccess</context>
  95. </contextlist>
  96. <override>AuthConfig</override>
  97.  
  98. <usage>
  99.     <p>The <directive>AuthDigestGroupFile</directive> directive sets
  100.     the name of a textual file containing the list of groups and their
  101.     members (user names). <var>File-path</var> is the absolute path to
  102.     the group file.</p>
  103.  
  104.     <p>Each line of the group file contains a groupname followed by
  105.     a colon, followed by the member usernames separated by spaces.
  106.     Example:</p>
  107.  
  108.     <example>mygroup: bob joe anne</example>
  109.  
  110.     <p>Note that searching large text files is <em>very</em>
  111.     inefficient.</p>
  112.  
  113.     <note type="warning"><title>Security:</title>
  114.     <p>Make sure that the <directive>AuthGroupFile</directive> is stored
  115.     outside the document tree of the web-server; do <em>not</em> put it in
  116.     the directory that it protects. Otherwise, clients may be able
  117.     to download the <directive>AuthGroupFile</directive>.</p>
  118.     </note>
  119. </usage>
  120. </directivesynopsis>
  121.  
  122. <directivesynopsis>
  123. <name>AuthDigestQop</name>
  124. <description>Determines the quality-of-protection to use in digest
  125. authentication</description>
  126. <syntax>AuthDigestQop none|auth|auth-int [auth|auth-int]</syntax>
  127. <default>AuthDigestQop auth</default>
  128. <contextlist><context>directory</context><context>.htaccess</context>
  129. </contextlist>
  130. <override>AuthConfig</override>
  131.  
  132. <usage>
  133.     <p>The <directive>AuthDigestQop</directive> directive determines
  134.     the <dfn>quality-of-protection</dfn> to use. <code>auth</code> will only do
  135.     authentication (username/password); <code>auth-int</code> is
  136.     authentication plus integrity checking (an MD5 hash of the entity
  137.     is also computed and checked); <code>none</code> will cause the module
  138.     to use the old RFC-2069 digest algorithm (which does not include
  139.     integrity checking). Both <code>auth</code> and <code>auth-int</code> may
  140.     be specified, in which the case the browser will choose which of
  141.     these to use. <code>none</code> should only be used if the browser for
  142.     some reason does not like the challenge it receives otherwise.</p>
  143.  
  144.     <note>
  145.       <code>auth-int</code> is not implemented yet.
  146.     </note>
  147. </usage>
  148. </directivesynopsis>
  149.  
  150. <directivesynopsis>
  151. <name>AuthDigestNonceLifetime</name>
  152. <description>How long the server nonce is valid</description>
  153. <syntax>AuthDigestNonceLifetime <var>seconds</var></syntax>
  154. <default>AuthDigestNonceLifetime 300</default>
  155. <contextlist><context>directory</context><context>.htaccess</context>
  156. </contextlist>
  157. <override>AuthConfig</override>
  158.  
  159. <usage>
  160.     <p>The <directive>AuthDigestNonceLifetime</directive> directive
  161.     controls how long the server nonce is valid. When the client
  162.     contacts the server using an expired nonce the server will send
  163.     back a 401 with <code>stale=true</code>. If <var>seconds</var> is
  164.     greater than 0 then it specifies the amount of time for which the
  165.     nonce is valid; this should probably never be set to less than 10
  166.     seconds. If <var>seconds</var> is less than 0 then the nonce never
  167.     expires. <!-- Not implemented yet: If <var>seconds</var> is 0 then
  168.     the nonce may be used exactly once by the client. Note that while
  169.     one-time-nonces provide higher security against replay attacks,
  170.     they also have significant performance implications, as the
  171.     browser cannot pipeline or multiple connections for the
  172.     requests. Because browsers cannot easily detect that
  173.     one-time-nonces are being used, this may lead to browsers trying
  174.     to pipeline requests and receiving 401 responses for all but the
  175.     first request, requiring the browser to resend the requests. Note
  176.     also that the protection against reply attacks only makes sense
  177.     for dynamically generated content and things like POST requests;
  178.     for static content the attacker may already have the complete
  179.     response, so one-time-nonces do not make sense here.  -->
  180.     </p>
  181. </usage>
  182. </directivesynopsis>
  183.  
  184. <directivesynopsis>
  185. <name>AuthDigestNonceFormat</name>
  186. <description>Determines how the nonce is generated</description>
  187. <syntax>AuthDigestNonceFormat <var>format</var></syntax>
  188. <contextlist><context>directory</context><context>.htaccess</context>
  189. </contextlist>
  190. <override>AuthConfig</override>
  191.  
  192. <usage>
  193.     <note>Not implemented yet.</note>
  194.     <!-- The AuthDigestNonceFormat directive determines how the nonce is
  195.     generated. -->
  196. </usage>
  197. </directivesynopsis>
  198.  
  199. <directivesynopsis>
  200. <name>AuthDigestNcCheck</name>
  201. <description>Enables or disables checking of the nonce-count sent by the
  202. server</description>
  203. <syntax>AuthDigestNcCheck On|Off</syntax>
  204. <default>AuthDigestNcCheck Off</default>
  205. <contextlist><context>server config</context></contextlist>
  206.  
  207. <usage>
  208.     <note>
  209.       Not implemented yet.
  210.     </note>
  211.     <!--
  212.     <p>The AuthDigestNcCheck directive enables or disables the checking of the
  213.     nonce-count sent by the server.</p>
  214.  
  215.     <p>While recommended from a security standpoint, turning this directive
  216.     On has one important performance implication. To check the nonce-count
  217.     *all* requests (which have an Authorization header, irrespective of
  218.     whether they require digest authentication) must be serialized through
  219.     a critical section. If the server is handling a large number of
  220.     requests which contain the Authorization header then this may noticeably
  221.     impact performance.</p>
  222.      -->
  223. </usage>
  224. </directivesynopsis>
  225.  
  226. <directivesynopsis>
  227. <name>AuthDigestAlgorithm</name>
  228. <description>Selects the algorithm used to calculate the challenge and
  229. response hases in digest authentication</description>
  230. <syntax>AuthDigestAlgorithm MD5|MD5-sess</syntax>
  231. <default>AuthDigestAlgorithm MD5</default>
  232. <contextlist><context>directory</context><context>.htaccess</context>
  233. </contextlist>
  234. <override>AuthConfig</override>
  235.  
  236. <usage>
  237.     <p>The <directive>AuthDigestAlgorithm</directive> directive
  238.     selects the algorithm used to calculate the challenge and response
  239.     hashes.</p>
  240.  
  241.     <note>
  242.       <code>MD5-sess</code> is not correctly implemented yet.
  243.     </note>
  244.     <!--
  245.     <p>To use <code>MD5-sess</code> you must first code up the
  246.     <code>get_userpw_hash()</code> function in
  247.     <code>mod_auth_digest.c</code>.</p>
  248.     -->
  249. </usage>
  250. </directivesynopsis>
  251.  
  252. <directivesynopsis>
  253. <name>AuthDigestDomain</name>
  254. <description>URIs that are in the same protection space for digest
  255. authentication</description>
  256. <syntax>AuthDigestDomain <var>URI</var> [<var>URI</var>] ...</syntax>
  257. <contextlist><context>directory</context><context>.htaccess</context>
  258. </contextlist>
  259. <override>AuthConfig</override>
  260.  
  261. <usage>
  262.     <p>The <directive>AuthDigestDomain</directive> directive allows
  263.     you to specify one or more URIs which are in the same protection
  264.     space (<em>i.e.</em> use the same realm and username/password info).
  265.     The specified URIs are prefixes, <em>i.e.</em> the client will assume
  266.     that all URIs "below" these are also protected by the same
  267.     username/password. The URIs may be either absolute URIs (<em>i.e.</em>
  268.     inluding a scheme, host, port, etc) or relative URIs.</p>
  269.  
  270.     <p>This directive <em>should</em> always be specified and
  271.     contain at least the (set of) root URI(s) for this space.
  272.     Omitting to do so will cause the client to send the
  273.     Authorization header for <em>every request</em> sent to this
  274.     server. Apart from increasing the size of the request, it may
  275.     also have a detrimental effect on performance if <directive
  276.     module="mod_auth_digest">AuthDigestNcCheck</directive> is on.</p>
  277.  
  278.     <p>The URIs specified can also point to different servers, in
  279.     which case clients (which understand this) will then share
  280.     username/password info across multiple servers without
  281.     prompting the user each time.</p>
  282. </usage>
  283. </directivesynopsis>
  284.  
  285. <directivesynopsis>
  286. <name>AuthDigestShmemSize</name>
  287. <description>The amount of shared memory to allocate for keeping track
  288. of clients</description>
  289. <syntax>AuthDigestShmemSize <var>size</var></syntax>
  290. <default>AuthDigestShmemSize 1000</default>
  291. <contextlist><context>server config</context></contextlist>
  292.  
  293. <usage>
  294.     <p>The <directive>AuthDigestShmemSize</directive> directive defines
  295.     the amount of shared memory, that will be allocated at the server
  296.     startup for keeping track of clients. Note that the shared memory
  297.     segment cannot be set less than the space that is neccessary for
  298.     tracking at least <em>one</em> client. This value is dependant on your
  299.     system. If you want to find out the exact value, you may simply
  300.     set <directive>AuthDigestShmemSize</directive> to the value of
  301.     <code>0</code> and read the error message after trying to start the
  302.     server.</p>
  303.  
  304.     <p>The <var>size</var> is normally expressed in Bytes, but you
  305.     may let the number follow a <code>K</code> or an <code>M</code> to
  306.     express your value as KBytes or MBytes. For example, the following
  307.     directives are all equivalent:</p>
  308.  
  309.     <example>
  310.       AuthDigestShmemSize 1048576<br />
  311.       AuthDigestShmemSize 1024K<br />
  312.       AuthDigestShmemSize 1M
  313.     </example>
  314. </usage>
  315. </directivesynopsis>
  316.  
  317. </modulesynopsis>
  318.